home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.lzh / wind12.prf < prev    next >
Text File  |  1987-06-23  |  18KB  |  385 lines
  1. .!****************************************************************************
  2. .! 
  3. .! ANTIC PUBLISHING INC., COPYRIGHT 1985.  REPRINTED BY PERMISSION.
  4. .!
  5. .! ** Professional GEM ** by Tim Oren
  6. .!
  7. .! Proff File by ST enthusiasts at
  8. .! Case Western Reserve University
  9. .! Cleveland, Ohio
  10. .! uucp : decvax!cwruecmp!bammi
  11. .! csnet: bammi@case
  12. .! arpa : bammi%case@csnet-relay
  13. .! compuserve: 71515,155
  14. .!
  15. .!****************************************************************************
  16. .!
  17. .!
  18. .!****************************************************************************
  19. .!
  20. .!            Begin Part 12
  21. .!
  22. .!****************************************************************************
  23. .!
  24. .PART XII GEM Events and Program Structure
  25. .PP
  26. So I fibbed a little.  This issue (#12) of ST PRO GEM started
  27. out to be another discussion of interface issues.  But, as Tolkien
  28. once said, the tale grew in the telling, and this is now the first
  29. of  a series of three articles.   This part will discuss AES event
  30. handling  and  its implications for GEM  program  structure.   The
  31. following  article will contain a "home brew" dialog handler  with
  32. some  new  features,  and  the third will,  finally,  take up  the
  33. discussion  of  interface design,  using the dialog handler as  an
  34. example.   (There is no download for this article.   The downloads
  35. will return, with a vengeance, in ST PRO GEM #13.)
  36.  
  37. .SH ALL FOR ONE, AND ONE FOR ALL.
  38. A quick inspection of the AES
  39. documents  shows that there are five routines devoted  to  waiting
  40. for individual types of events, and one routine, evnt_multi, which
  41. is  used  when more than one type is desired.   This article  will
  42. discuss  ONLY evnt_multi for two reasons.   First,  it is the most
  43. frequently used of the routines.   Second, waiting for one type of
  44. event is a bad practice.   Any event call turns the system over to
  45. the AES and suspends the application and its interaction with  the
  46. user.   In  such  cases,  some  "escape clause",  such as a timer,
  47. should be inserted to revive the program and prompt the user if no
  48. event  is  forthcoming.   Otherwise,  the  application may end  up
  49. apparently  (or  actually)  hung,  with a  resulting  reboot,  and
  50. probably a very annoyed user.
  51. .SH STARTING  AHEAD.
  52. One  possible type of event is a  message.
  53. Messages  are usually sent to the application by the AES,  and are
  54. associated  with  windows or the menu.   Two previous articles  in
  55. this  series have discussed such messages.   ST PRO GEM number two
  56. considered   window  messages,   and  number  seven  handled  menu
  57. messages.  You may want to review these topics before proceeding.
  58. .PP
  59. The actual evnt_multi call is a horrendous thing:
  60. .FB evnt_multi()
  61. ev_which = evnt_multi(ev_flags,
  62.            btn_clicks, btn_mask, btn_state,
  63.            r1_flags, r1_x, r1_y, r1_w, r1_h,
  64.            r2_flags, r2_x, r2_y, r2_w, r2_h,
  65.            &msg_buff,
  66.            time_lo, time_hi,
  67.            &mx, &my, &btn, &kbd, &char, &clicks);
  68. .FE
  69. Each  of  the lines in the call relate to a different  event,  and
  70. they  will be discussed in the order in which they  appear.
  71. .PP
  72. Note  that a call with this number of parameters causes  some
  73. overhead stacking and retrieval of the values.   In  most
  74. cases,  this  should be of little concern on a machine as fast  as
  75. the ST.   However, where throughput is a concern, such as in close
  76. tracking  of the mouse cursor,  you may want to write a customized
  77. binding  for evnt_multi which dispenses with the  parameter  list.
  78. This  can  be accomplished by maintaining the values in  a  static
  79. array  and moving them as a block into the binding  arrays  int_in
  80. (for all values but &msg_buff), and addr_in (for &msg_buff).  Note
  81. that  you  may NOT simply leave the values in  int_in;  other  AES
  82. bindings reuse this space.
  83. .PP
  84. Ev_flags  and ev_which are both 16-bit integers  composed  of
  85. flag bits.  Bits set in ev_flags determine which event(s) the call
  86. will  wait  for;  those  set in ev_which  indicate  what  event(s)
  87. actually occurred.   Both use the following flag bit mnemonics and
  88. functions:
  89. .BO
  90.      0x0001 - MU_KEYBD - Keyboard input
  91. .EO
  92. .BO
  93.      0x0002 - MU_BUTTON - Mouse button(s)
  94. .EO
  95. .BO
  96.      0x0004 - MU_M1 - Mouse rectangle #1
  97. .EO
  98. .BO
  99.      0x0008 - MU_M2 - Mouse rectangle #2
  100. .EO
  101. .BO
  102.      0x0010 - MU_MESAG - AES message
  103. .EO
  104. .BO
  105.      0x0020 - MU_TIMER - Timer
  106. .EO
  107. .sp 1
  108. The  appropriate mnemonics are ORed together to create the  proper
  109. ev_flags value.
  110. .PP
  111. There  is  one  common pitfall here.   Notice  that  multiple
  112. events  may  be reported from one evnt_multi.   Event  merging  is
  113. performed  by the AES in order to save space on the  application's
  114. event queue.   If events have been merged,  more than one bit will
  115. be  set in the ev_which word.   Your application must check ALL of
  116. the  bits  before  returning to a new  evnt_multi  call.   If  you
  117. don't do this, some events may be effectively lost.
  118. .PP
  119. The  first event to be considered is the mouse button.   This
  120. is probably the most difficult event to understand and use, and it
  121. has one major shortcoming.
  122. .PP
  123. The  parameter  btn_clicks tells GEM the  maximum  number  of
  124. clicks which you are interested in seeing.   This value is usually
  125. two,  if your program uses the double-click method, or one if only
  126. single  clicks  are used.   The AES returns the number  of  clicks
  127. which caused the event through &clicks, which must be a pointer to
  128. a word.
  129. .PP
  130. GEM determines the number of clicks by the following  method.
  131. When the first button-down is detected, a time delay is begun.  If
  132. another  complete button-up,  button-down cycle is detected before
  133. the time expires,  then the result is a double click.   Otherwise,
  134. the  event is a single click.    Note that the final state of  the
  135. buttons  is  returned via &btn,  as described below.   By checking
  136. this  final state,  you may determine whether a single click event
  137. ended with the button up (a full click),  or with the button still
  138. down  (which  may  be  interpreted as  the  beginning  of  a  drag
  139. operation).   Double clicking is meaningless,  and not checked, if
  140. the evnt_multi is waiting on more than one button (see below).
  141. .PP
  142. The double-click detection delay is variable,  and may be set
  143. by your program using the call
  144. .FB ev_dclick()
  145. ev_dspeed = ev_dclick(ev_dnew, ev_dfunc);
  146. .FE
  147. Ev_dfunc  is a flag which determines the purpose of the call.   If
  148. it  is  zero,  the  current  double click  speed  is  returned  in
  149. ev_dspeed.   If ev_dfunc is non-zero, then ev_dnew becomes the new
  150. double-click   speed.    Both  ev_dspeed  and  ev_dnew  are  words
  151. containing  a "magic number" between zero and four.   Zero is  the
  152. slowest  (i.e.,  longest)  double-click,  and four is the fastest.
  153. (These  correspond  to  the  slow-fast  range  in  the   Desktop's
  154. Preferences  dialog.)  In general,  you should not reset the click
  155. speed  unless  specifically requested,  because such a change  can
  156. throw off the user's timing and destroy the hand/eye  coordination
  157. involved in using the mouse.
  158. .PP
  159. GEM  was  originally designed to work with  a  single  button
  160. input device.   This allows GEM applications interaction well with
  161. devices such as light pens and digitizing tablets.   However, some
  162. features are available for dealing with multi-button mice like the
  163. ST's.
  164. .PP
  165. The  evnt_multi parameters btn_mask and btn_state  are  words
  166. containing  flag bits corresponding to buttons.   The lowest order
  167. bit corresponds to the left-most button,  and so on.  A bit is set
  168. in  the  btn_mask parameter if the AES is to  watch  a  particular
  169. button.   The  corresponding bit in btn_state is set to the  value
  170. for  which  the program is waiting.   The word returned  via  &btn
  171. uses  the  same  bit system to show the state of  the  buttons  at
  172. completion.   It  is  important to notice that all of  the  target
  173. states in btn_state must occur SIMULTANEOUSLY for the event to  be
  174. triggered.
  175. .PP
  176. Note the limiting nature of this last statement.  It prevents
  177. a  program from waiting for EITHER the left or right button to  be
  178. pressed.  Instead, it must wait for BOTH to be pressed, which is a
  179. difficult  operation  at best.   As a result,  the standard  mouse
  180. button  procedure is practically useless if you want to take  full
  181. advantage  of  both buttons o